feat: add Chrome DevTools MCP Runloop blueprint and headless Linux docs #9005
Conversation
sestinj
requested review from
Patrick-Erichsen
and removed request for
a team
|
Keep this PR in a mergeable state → Learn moreAll Green is an AI agent that automatically: ✅ Addresses code review comments ✅ Fixes failing CI checks ✅ Resolves merge conflicts |
1 similar comment
|
Keep this PR in a mergeable state → Learn moreAll Green is an AI agent that automatically: ✅ Addresses code review comments ✅ Fixes failing CI checks ✅ Resolves merge conflicts |
dosubot
bot
added
the
size:XL
|
|
✅ Review Complete Code Review: PR #9005 - Chrome DevTools MCP Blueprint SetupOverviewThis PR adds Runloop blueprint configuration and documentation for Chrome DevTools MCP development in headless Linux environments. The changes enable automated setup of Chromium, Xvfb, and required symlinks for the Chrome DevTools MCP server. Issues & Recommendations1. Package name inconsistency across filesLocation: Multiple files
Issue: Different Ubuntu/Debian versions use different package names. Solution: Standardize on the most compatible package names. For Ubuntu 22.04+, use:
Update 2. Symlink path inconsistencyLocation:
Issue: The symlink source differs, which could cause "Chrome executable not found" errors depending on which file is used. Solution: Align both to use 3. Timing race condition in launch commandsLocation: "launch_commands": [
"nohup Xvfb :99 -screen 0 1920x1080x24 > /tmp/xvfb.log 2>&1 &",
"sleep 2"
]Issue: The 2-second sleep is a hardcoded delay that may not be sufficient on slower systems or may waste time on faster systems. Recommendation: Add explicit verification that Xvfb is ready: "launch_commands": [
"nohup Xvfb :99 -screen 0 1920x1080x24 > /tmp/xvfb.log 2>&1 &",
"timeout 10 bash -c 'until xdpyinfo -display :99 >/dev/null 2>&1; do sleep 0.5; done'"
]Note: This requires 4. Missing error handling in Python scriptLocation: Issue: The blueprint refresh logic assumes the blueprint will be found in the list, but doesn't handle the case where it's not found. If the list doesn't contain the blueprint, the loop will silently continue with stale data. Solution: Add error handling: found = False
for bp in blueprints:
if bp.id == blueprint.id:
blueprint = bp
found = True
break
if not found:
print(f"Warning: Blueprint {blueprint.id} not found in list")5. TypeScript status value mismatchLocation: while (info.status !== "build_complete" && info.status !== "build_failed")vs Python version (line 71): while blueprint.status not in ["ready", "failed"]:Issue: Status values differ between implementations ("ready" vs "build_complete", "failed" vs "build_failed"). This suggests one implementation may be using incorrect API values. Solution: Verify the correct status values from the Runloop API documentation and standardize both scripts. 6. Missing dependency in troubleshooting documentationLocation: The troubleshooting section suggests using commands like Issue: Solution: Add 7. Hardcoded user paths in generated scriptsLocation: Python/TypeScript scripts lines 40-45 RUN echo '#!/bin/bash\\n\\
...
sleep 2' > /home/user/start-xvfb.sh && \\
chmod +x /home/user/start-xvfb.shMinor concern: Uses hardcoded Minor Suggestions
SummaryThe PR provides good infrastructure for Chrome DevTools MCP development, but has critical package naming and symlink inconsistencies that will cause failures in different environments. The primary fixes needed:
The documentation is comprehensive and well-structured. After addressing the issues above, this will be a solid addition. |
…ls MCP guide - Add comprehensive headless Linux setup section with Xvfb configuration - Document Runloop blueprint scripts for automated devbox setup - Include GitHub Actions setup examples for CI/CD integration - Add troubleshooting guide for common headless environment issues - Reference new RUNLOOP_BLUEPRINT_README.md and linux-setup.md files Generated with [Continue](https://continue.dev) Co-Authored-By: Continue <[email protected]> Co-authored-by: nate <[email protected]>
Documentation Updates AddedI've reviewed the PR changes and added documentation updates to keep the docs current with the new infrastructure: Changes Made**Updated: ** Added a new "Headless Linux Setup" section (as an accordion to avoid cluttering the main flow) that documents:
RationaleThe PR adds significant infrastructure for running Chrome DevTools MCP in headless environments (Runloop blueprints, GitHub Actions workflow updates, setup scripts), but the existing Chrome DevTools MCP guide only covered local desktop usage. This update ensures developers working in CI/CD or cloud development environments can find the setup instructions they need. The documentation is scoped to match the PR's changes - it references the new files without duplicating their content, and maintains the guide's existing level of detail. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (all 1 issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="docs/guides/chrome-devtools-mcp-performance.mdx">
<violation number="1" location="docs/guides/chrome-devtools-mcp-performance.mdx:116">
P2: The `DISPLAY` environment variable set via step-level `env:` won't persist to subsequent steps. Chrome DevTools MCP steps that follow will fail because `DISPLAY` won't be set. Use `echo "DISPLAY=:99" >> $GITHUB_ENV` to persist across steps.</violation>
</file>
Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR
| run: | | ||
| Xvfb :99 -screen 0 1920x1080x24 & | ||
| sleep 2 | ||
| env: |
There was a problem hiding this comment.
P2: The DISPLAY environment variable set via step-level env: won't persist to subsequent steps. Chrome DevTools MCP steps that follow will fail because DISPLAY won't be set. Use echo "DISPLAY=:99" >> $GITHUB_ENV to persist across steps.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/guides/chrome-devtools-mcp-performance.mdx, line 116:
<comment>The `DISPLAY` environment variable set via step-level `env:` won't persist to subsequent steps. Chrome DevTools MCP steps that follow will fail because `DISPLAY` won't be set. Use `echo "DISPLAY=:99" >> $GITHUB_ENV` to persist across steps.</comment>
<file context>
@@ -50,6 +50,89 @@ For all options, first:
+ run: |
+ Xvfb :99 -screen 0 1920x1080x24 &
+ sleep 2
+ env:
+ DISPLAY: ":99"
+ ```
</file context>
✅ Addressed in 0c975cf
There was a problem hiding this comment.
3 issues found across 6 files
Prompt for AI agents (all 3 issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="Dockerfile.devbox">
<violation number="1" location="Dockerfile.devbox:27">
P2: The entrypoint script creation using `echo` with `\n` escape sequences is fragile and shell-dependent. Consider using a heredoc for better readability and portability:
```dockerfile
RUN cat > /entrypoint.sh <<'EOF'
#!/bin/bash
# Start Xvfb in the background
Xvfb :99 -screen 0 1920x1080x24 &
# Wait a moment for Xvfb to start
sleep 2
# Execute the command passed to docker run
exec "$@"
EOF
chmod +x /entrypoint.sh
```</violation>
</file>
<file name="create_chrome_devtools_blueprint.ts">
<violation number="1" location="create_chrome_devtools_blueprint.ts:34">
P2: Inconsistent use of `sudo` in Dockerfile - apt-get runs without sudo but mkdir/ln use sudo. If running as root, sudo is unnecessary; if running as non-root, apt-get would fail.</violation>
<violation number="2" location="create_chrome_devtools_blueprint.ts:69">
P2: Polling loop lacks a timeout or maximum retry count, which could cause the script to hang indefinitely if the build never reaches a terminal state.</violation>
</file>
Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR
Dockerfile.devbox
Outdated
| RUN echo '#!/bin/bash\n\ | ||
| # Start Xvfb in the background\n\ | ||
| Xvfb :99 -screen 0 1920x1080x24 &\n\ | ||
| # Wait a moment for Xvfb to start\n\ | ||
| sleep 2\n\ | ||
| # Execute the command passed to docker run\n\ | ||
| exec "$@"' > /entrypoint.sh && \ | ||
| chmod +x /entrypoint.sh |
There was a problem hiding this comment.
P2: The entrypoint script creation using echo with \n escape sequences is fragile and shell-dependent. Consider using a heredoc for better readability and portability:
RUN cat > /entrypoint.sh <<'EOF'
#!/bin/bash
# Start Xvfb in the background
Xvfb :99 -screen 0 1920x1080x24 &
# Wait a moment for Xvfb to start
sleep 2
# Execute the command passed to docker run
exec "$@"
EOF
chmod +x /entrypoint.shPrompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At Dockerfile.devbox, line 27:
<comment>The entrypoint script creation using `echo` with `\n` escape sequences is fragile and shell-dependent. Consider using a heredoc for better readability and portability:
```dockerfile
RUN cat > /entrypoint.sh <<'EOF'
#!/bin/bash
# Start Xvfb in the background
Xvfb :99 -screen 0 1920x1080x24 &
# Wait a moment for Xvfb to start
sleep 2
# Execute the command passed to docker run
exec "$@"
EOF
chmod +x /entrypoint.sh
```</comment>
<file context>
@@ -0,0 +1,43 @@
+ ln -s /usr/bin/chromium-browser /opt/google/chrome/chrome
+
+# Create a startup script to run Xvfb
+RUN echo '#!/bin/bash\n\
+# Start Xvfb in the background\n\
+Xvfb :99 -screen 0 1920x1080x24 &\n\
</file context>
| RUN echo '#!/bin/bash\n\ | |
| # Start Xvfb in the background\n\ | |
| Xvfb :99 -screen 0 1920x1080x24 &\n\ | |
| # Wait a moment for Xvfb to start\n\ | |
| sleep 2\n\ | |
| # Execute the command passed to docker run\n\ | |
| exec "$@"' > /entrypoint.sh && \ | |
| chmod +x /entrypoint.sh | |
| RUN cat > /entrypoint.sh <<'EOF' | |
| #!/bin/bash | |
| # Start Xvfb in the background | |
| Xvfb :99 -screen 0 1920x1080x24 & | |
| # Wait a moment for Xvfb to start | |
| sleep 2 | |
| # Execute the command passed to docker run | |
| exec "$@" | |
| EOF | |
| chmod +x /entrypoint.sh |
✅ Addressed in a693347
create_chrome_devtools_blueprint.ts
Outdated
| # Create symlink for Chrome DevTools MCP | ||
| # The MCP looks for Chrome at /opt/google/chrome/chrome | ||
| RUN sudo mkdir -p /opt/google/chrome && \\ |
There was a problem hiding this comment.
P2: Inconsistent use of sudo in Dockerfile - apt-get runs without sudo but mkdir/ln use sudo. If running as root, sudo is unnecessary; if running as non-root, apt-get would fail.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At create_chrome_devtools_blueprint.ts, line 34:
<comment>Inconsistent use of `sudo` in Dockerfile - apt-get runs without sudo but mkdir/ln use sudo. If running as root, sudo is unnecessary; if running as non-root, apt-get would fail.</comment>
<file context>
@@ -0,0 +1,105 @@
+
+# Create symlink for Chrome DevTools MCP
+# The MCP looks for Chrome at /opt/google/chrome/chrome
+RUN sudo mkdir -p /opt/google/chrome && \\
+ sudo ln -s /usr/bin/chromium /opt/google/chrome/chrome
+
</file context>
✅ Addressed in a693347
| console.log("Waiting for blueprint to build..."); | ||
| let info = await blueprint.get_info(); | ||
|
|
||
| while (info.status !== "build_complete" && info.status !== "build_failed") { |
There was a problem hiding this comment.
P2: Polling loop lacks a timeout or maximum retry count, which could cause the script to hang indefinitely if the build never reaches a terminal state.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At create_chrome_devtools_blueprint.ts, line 69:
<comment>Polling loop lacks a timeout or maximum retry count, which could cause the script to hang indefinitely if the build never reaches a terminal state.</comment>
<file context>
@@ -0,0 +1,105 @@
+ console.log("Waiting for blueprint to build...");
+ let info = await blueprint.get_info();
+
+ while (info.status !== "build_complete" && info.status !== "build_failed") {
+ await new Promise((resolve) => setTimeout(resolve, 5000));
+ info = await blueprint.get_info();
</file context>
✅ Addressed in a693347
Use GITHUB_ENV to persist DISPLAY variable instead of step-level env so Chrome DevTools MCP can access it in subsequent workflow steps. Generated with [Continue](https://continue.dev) Co-Authored-By: Continue <[email protected]> Co-authored-by: nate <[email protected]>
Review Issue Fixed ✅Issue: The Root Cause: Using Fix: Changed to use Commit: 0c975cf Thank you for catching this! The documentation example now correctly shows the proper way to set persistent environment variables in GitHub Actions workflows. |
- Use heredoc for entrypoint script creation (more readable and portable) - Remove unnecessary sudo commands in Dockerfile (running as root) - Add timeout to blueprint build polling loops (prevents infinite hangs) Addresses review feedback from cubic-dev-ai. Generated with [Continue](https://continue.dev) Co-Authored-By: Continue <[email protected]> Co-authored-by: nate <[email protected]>
There was a problem hiding this comment.
1 issue found across 3 files (changes from recent commits).
Prompt for AI agents (all 1 issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="create_chrome_devtools_blueprint.ts">
<violation number="1" location="create_chrome_devtools_blueprint.ts:74">
P2: Returning `null` on timeout causes the script to exit with code 0 (success). Consider throwing an error instead so the `.catch()` handler can exit with code 1, or check the return value in `.then()` to determine the correct exit code.</violation>
</file>
Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR
create_chrome_devtools_blueprint.ts
Outdated
| while (info.status !== "build_complete" && info.status !== "build_failed") { | ||
| if (retries >= maxRetries) { | ||
| console.error("Blueprint build timed out after 5 minutes"); | ||
| return null; |
There was a problem hiding this comment.
P2: Returning null on timeout causes the script to exit with code 0 (success). Consider throwing an error instead so the .catch() handler can exit with code 1, or check the return value in .then() to determine the correct exit code.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At create_chrome_devtools_blueprint.ts, line 74:
<comment>Returning `null` on timeout causes the script to exit with code 0 (success). Consider throwing an error instead so the `.catch()` handler can exit with code 1, or check the return value in `.then()` to determine the correct exit code.</comment>
<file context>
@@ -62,14 +62,21 @@ WORKDIR /home/user
while (info.status !== "build_complete" && info.status !== "build_failed") {
+ if (retries >= maxRetries) {
+ console.error("Blueprint build timed out after 5 minutes");
+ return null;
+ }
await new Promise((resolve) => setTimeout(resolve, 5000));
</file context>
| return null; | |
| throw new Error("Blueprint build timed out after 5 minutes"); |
✅ Addressed in 660919e
continue
bot
changed the title
- Throw Error instead of returning null on timeout in TypeScript - Throw TimeoutError/RuntimeError instead of returning None in Python - Add proper error handling in Python main block - Ensures scripts exit with code 1 on failure Addresses review feedback from cubic-dev-ai. Generated with [Continue](https://continue.dev) Co-Authored-By: Continue <[email protected]> Co-authored-by: nate <[email protected]>
CI Status UpdateThe failing test job () is due to flaky TUI rendering tests that are unrelated to the changes in this PR:
Why these failures are unrelated:
Request: Could a maintainer with permissions rerun the failing job, or merge if the changes look good? The PR is functionally complete and all core functionality is validated by the passing test suites. Thanks! 🙏 |
RomneyDa
left a comment
RomneyDa
left a comment
There was a problem hiding this comment.
Ignore previous comment, didn't fully grok that these were docs. Might consider moving the scripts into some nested examples folder or similar
Description
This PR adds Runloop Blueprint infrastructure and documentation for running Chrome DevTools MCP in headless Linux environments (CI/CD, devboxes, servers).
What Changed
New Files:
RUNLOOP_BLUEPRINT_README.md- Comprehensive guide for creating and using Runloop blueprintslinux-setup.md- Manual headless Linux setup instructionscreate_chrome_devtools_blueprint.py- Python script to create/publish the blueprintcreate_chrome_devtools_blueprint.ts- TypeScript script to create/publish the blueprintDockerfile.devbox- Reference Docker configurationUpdated Files:
.github/workflows/runloop-blueprint-template.json- Blueprint configuration with Chrome/Xvfb setupdocs/guides/chrome-devtools-mcp-performance.mdx- Added headless Linux setup section with:Key Improvements
AI Code Review
@continue-reviewChecklist
Screen recording or screenshot
N/A - Infrastructure and documentation updates
Tests
Manual testing performed:
This agent session was co-authored by nate and Continue.
Summary by cubic
Adds a headless Chrome DevTools MCP blueprint and tooling to run Chromium via Xvfb in Runloop devboxes and CI. Improves reliability of MCP tools on Ubuntu/ARM64 and documents setup and usage.
New Features
Migration
Written for commit 660919e. Summary will update automatically on new commits.